package com.binarysoft.service.common.mq;

import java.util.Collection;
import java.util.Map;

import javax.jms.MessageListener;

import common.framework.dsb.DynamicService;

/**
 * 封装了对Java Message Service (MQ)的消息发送和接收。 实现了连接池操作模式和失效重连机制。
 * 本连接池可以通过参数配置，实现对多个Active-MQ
 * 实例的统一管理，类似于MultipleConnectionPoolService能够实现对多个数据库进行连接管理一样。
 * 
 * @author david
 * 
 */
public interface MessageQueueService extends DynamicService {
	int AUTO_ACKNOWLEDGE = 1;
	int CLIENT_ACKNOWLEDGE = 2;
	int DUPS_OK_ACKNOWLEDGE = 3;

	int NON_PERSISTENT = 1;
	int PERSISTENT = 2;

	/**
	 * List pools.
	 * 
	 * @return
	 * @throws Exception
	 */
	Map<String, MQService> listPools() throws Exception;

	/**
	 * List destinations.
	 * 
	 * @return
	 * @throws Exception
	 */
	Map<String, MQDestination> listDestinations() throws Exception;

	/**
	 * List consumer reconnect tasks.
	 * 列出队列消费者重连接任务，正常的情况下，重连接任务队列应该是空的，只有当Active-MQ服务停止后，才出现重新连接任务
	 * 
	 * @return
	 * @throws Exception
	 */
	Collection<ConnectTask> listReconnectTask() throws Exception;

	/**
	 * 待处理的消息数(接收消息并缓存的消息数)
	 * 本连接池管理的所有的队列，接收的所有消息均放置在缓冲队列中，为防止内存溢出，设置max.pending.length变量
	 * ，超出max.pending
	 * .length时，收到的消息将丢弃，正常的情况下，这个对列不应该出现累积消息，一旦出现累积消息，说明consumer处理消息过慢
	 * 
	 * @return
	 */
	int pendingMsgs();

	/**
	 * Receive message. 启动消息接收
	 * 目前支持一个队列一个监听器的模式，即最后注册的MessageListener能够收到消息
	 * 
	 * @param pool_name
	 * @param queue
	 * @param listener
	 * @throws Exception
	 */
	void receive(String pool_name, String queue, MessageListener listener) throws Exception;

	/**
	 * Stop receiving. 当消息客户端由于消息存储出现故障或者其它原因，希望停止接收消息时，调用次方法。
	 * 这个方法一旦被调用，则发送端发送的消息会被缓存在消息队列中，消息服务本身具备持久化功能。
	 * 
	 * @param pool_name
	 * @param queue
	 * @throws Exception
	 */
	void stop(String pool_name, String queue) throws Exception;

	/**
	 * Send object message.
	 * 
	 * @param pool_name
	 * @param queue
	 * @param map
	 * @throws Exception
	 */
	void send(String pool_name, String queue, final Map<String, Object> map) throws Exception;

	/**
	 * Send text message.
	 * 
	 * @param pool_name
	 * @param queue
	 * @param text
	 * @throws Exception
	 */
	void send(String pool_name, String queue, String text) throws Exception;
}
